#-*- coding: utf-8 -*-

#This file is part of pyLot library.
#
# pyLot is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# pyLot is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with pyLot.  If not, see <http://www.gnu.org/licenses/>.

__author__ = u'Pierre Puiseux, Guillaume Baty'
__copyright__ = u"Copyright 2011-2012 (C) andheo, Université de Pau et des Pays de l'Adour"
__credits__ = [u'Pierre Puiseux', u'Guillaume Baty']
__license__ = "GNU Lesser General Public License"

__all__ = ['INature']

from traits.api import Interface, Bool, Str

class INature (Interface):
  u"""
  INature is used to extends datum.
  It allows to add new types to Container/Datum.
  """
  advanced = Bool
  identifier = Str

  def __init__(self, value):
    u"""
    Exactly ONE argument required. Default value allowed.
    
    Constructor should support unicode repr of object as initial value :
    
    Example ::
      c1 = Coordinate([1,2,3])
      cu = unicode(c)          # cu == u'(1.0, 2.0, 3.0)'
      c2 = Coordinate(cu)      # c2 == c1
      c3 = eval(repr(c2))      # c3 == c2

    If type doesn't support unicode in constructor :
      - set DatumType.advanced attribute to True
      - Constructor must raise an ErrNoUnicodeConstructor error if user passes an unicode
      - toXmlElement/fromXmlElement MUST be defined
 
    Thanks to these properties, a valid type can be serialized automatically to xml.
    Simple types (advanced = False or advanced not defined) can also be serialized to 
      - ini format
      - conf (light xml)
    """

  def __copy__(self):
    u"""
    Returns a copy of current object.
    This method is called using copy.copy function
    """

  def __deepcopy__(self):
    u"""
    Returns a deep copy of current object.
    As DatumType are simple objects (like int or unicode), deepcopy and copy
    are generally equivalent.
    This method is called using copy.deepcopy function.
    """

  def __repr__(self):
    u"""    
    Object python representation
    
    >>> obj = DatumTypeSample()
    >>> eval(repr(obj)) == obj #+SKIP
    True
    
    For example, a repr for a coordinate object can be 'Coordinate([1,0,0])'   
    """

  def __unicode__(self):
    u"""
    For example, a repr for a coordinate object can be 'Coordinate([1,0,0])'
    
    .. seealso ::
    
      INature main doc
    """

class IPyLotNature(INature):

  @classmethod
  def FromCsv (cls, src):
    u"""
    Optionnal: implements this method if you want to support pyLot CSV serialization.
    This classmethod returns a new object.
    See also upFromCsv, toCsv.
    """

  @classmethod
  def FromPyLot (cls, src):
    u"""
    Optionnal: implements this method if you want to support pyLot format serialization.
    This classmethod returns a new object.
    See also upFromPyLot, toPyLot.
    """

  def upFromPyLot (self, src):
    pass

  def upFromCsv (self, src):
    pass

  def toPyLot (self):
    u"""
    See pyLot format documentation
    """

  @classmethod
  def toCsv (self):
    u"""
    See pyLot csv format documentation
    """


if __name__ == '__main__' :
  pass
